.\" Process this file with
.\" groff -man -Tascii foo.1
.\"
.TH MONETDB 1 "NOVEMBER 2012" MonetDB "MonetDB Applications"
.SH NAME
monetdb \- control a MonetDB Database Server instance
.SH SYNOPSIS
.B monetdb
[
.I monetdb_options
]
.I command
[
.I command_options
] [
.I command_args
]
.SH DESCRIPTION
.I Monetdb
allows an administrator of the MonetDB Database Server to perform
various operations on the databases in the server.  It relies on
.IR monetdbd (1)
running in the background for all operations.
.SH OPTIONS
.I Monetdb_options
affect all commands and control the general behavior of
.IR monetdb .
.TP
.B \-q
Suppresses all standard progress messages, only writing output to stderr
if an error occurred.
.TP
\fB\-h\fP \fIhostname\fP
Connect to
.I hostname
instead of attempting a connection over the local UNIX socket.  This
allows
.I monetdb
to connect to a remote
.IR monetdbd (1).
The use of this option requires
.B \-P
(see below).
.TP
\fB\-p\fP \fIport\fP
Connects to the given portnumber instead of the default (50000).
Requires
.B \-h
to be given as option too.
.TP
\fB\-P\fP \fIpassphrase\fP
Specifies the passphrase necessary to login to a remote
.IR monetdbd (1).
This option requires \-h to be given as well.  A bad passphrase causes
.I monetdb
to fail to login, and hence fail to perform any remote action.
.TP
.B \-v
Show version, equal to
.BR "monetdb version" .
.SH COMMANDS
The commands for the
.I monetdb
utility are
.BR create ,
.BR destroy ,
.BR lock ,
.BR release ,
.BR status ,
.BR start ,
.BR stop ,
.BR kill ,
.BR set ,
.BR get ,
.BR inherit ,
.BR discover ,
.BR help ,
and
.BR version .
The commands facilitate adding, removing, maintaining, starting and
stopping a database inside the MonetDB Database Server.
.P
For all commands, database arguments can be glob-like expressions.
This allows to do wildcard matches.  For details on the syntax, see
.IR EXPRESSIONS .
.TP
\fBcreate\fP [\fB\-m\fP \fIpattern\fP]  [\fB\-p\fP \fIpassword\fB] \fIdatabase\fP [\fIdatabase\fP ...]
Initializes a new database in the MonetDB Database Server.  A database
created with this command makes it available under its database name,
but not yet for use by clients, as the database is put into maintenance
mode.  This allows the database administrator to perform initialization
steps before releasing it to users, unless the
.B \-p
argument is supplied.  See also
.BR "monetdb lock" .
The name of the database must match the expression [A\-Za\-z0\-9\-_]+.
.TP
\fB\-m\fP \fIpattern\fP
With the
.B \-m
flag, instead of creating a database, a multiplex-funnel is created.
See section
.I MULTIPLEX-FUNNEL
in
.IR monetdbd (1).
The pattern argument is not fully the same as a pattern for connecting
or discovery.  Each parallel target for the multiplex-funnel is given as
\fIusername\fP\fB+\fP\fIpassword\fP\fB@\fP\fIpattern\fP
sequence, separated by commas.  Here the
.I pattern
is an ordinary pattern as would be used for connecting to a database,
and can hence also be just the name of a database.
.TP
\fB\-p\fP \fIpassword\fB
The
.B \-p
flag allows to create a database with the given password for the monetdb
user.  Since this protects the database from being accessed via
well-known credentials, the created database is not locked after
creation.  This way, a new database can be created and used right away
using the password supplied.
.TP
\fBdestroy\fP [\fB\-f\fP] \fIdatabase\fP [\fIdatabase\fP ...]
Removes the given
.IR database ,
including all its data and logfiles.  Once
destroy has completed, all data is lost.  Be careful when using this
command.
.TP
.B \-f
By default, a confirmation question is asked, however the
.B \-f
option, when provided, suppresses this question and removal is executed
right away.  Note that without this option you cannot destroy a running
database, bring it down first using the
.B stop
command.
.TP
\fBlock\fP \fIdatabase\fP [\fIdatabase\fP ...]
Puts the given database in maintenance mode.  A database under
maintenance can only be connected to by an administrator account
(by default the
.I monetdb
account).  A database which is under maintenance is not started
automatically by
.IR monetdbd (1),
the MonetDB Database Server, when clients request for it.  Use the
.B release
command to bring the database back for normal usage.  To start a
database which is under maintenance for administrator access, the
.B start
command can be used.
.TP
\fBrelease\fP \fIdatabase\fP [\fIdatabase\fP ...]
Brings back a database from maintenance mode.  A released database is
available again for normal use by any client, and is started on demand.
Use the
.B lock
command to take a database under maintenance.
.TP
\fBstatus\fP [\fB\-lc\fP] [\fB\-s\fP \fIstates\fP] [\fIdatabase\fP ...]
Shows the state of the given database, or, when none given, all known
databases.
Three modes control the level of detail in the displayed
output.  By default a condensed one-line output per database format is
used.  This output resembles pretty much the output of various
.I xxxstat
programs, and is ideal for quickly gaining an overview of the system
state.  The output is divided into four columns,
.BR name ,
.BR state ,
.BR health ,
and
.BR remarks .
The
.B state
column contains two characters that identify the state of the
database, based on Booting (starting up), Running, Stopped, Crashed and
Locked (under maintenance).  This is followed by the uptime when
running.  The
.B health
column contains the percentage of successful starts
and stops, followed by the average uptime.  The
.B remarks
column can
contain arbitrary information about the database state, but usually
contains the URI the database can be connected to.
.RS
.TP
.B \-c
The
.B \-c
flag shows the most used properties of a database.  This includes the
state of the database (running, crashed, stopped), whether it is under
maintenance or not, the crash averages and uptime statistics.  The crash
average is the number of times the database has crashed over the last 1,
15 or 30 starts.  The lower the average, the healthier the database is.
.TP
.B \-l
Triggered by the
.B \-l
flag, a long listing is used.  This listing spans many rows with on each
row one property and its value separated by a colon
.RB ( : ).
The long listing includes all information that is available.
.TP
.B \-s
The
.B \-s
flag controls which databases are being shown, matching their state.
The required argument to this flag can be a combination of any of the
following characters.  Note that the order in which they are put also
controls the order in which the databases are printed.
.BR b ,
.BR r ,
.BR s ,
.BR c ,
and
.B l
are used to print a starting up (booting), started (running), stopped,
crashed and locked database respectively.  The default order which is
used when the
.B \-s
flag is absent, is
.B rbscl.
.RE
.TP
\fBstart\fP [\fB\-a\fP] \fIdatabase\fP [\fIdatabase\fP ...]
.PD 0
.TP
\fBstop\fP [\fB\-a\fP] \fIdatabase\fP [\fIdatabase\fP ...]
.PD 0
.TP
\fBkill\fP [\fB\-a\fP] \fIdatabase\fP [\fIdatabase\fP ...]
Starts, stops or kills the given database, or, when
.B \-a
is supplied, all known databases.  The
.B kill
command immediately sends a SIGKILL and should only be used as last
resort for a database that doesn't respond any more.  Killing a database
may result in (partial) data loss.
It is more common to use the
.B stop
command to stop a database.  It will first attempt to stop the database,
waiting for
.B mero_exittimeout
seconds and if that fails, kill the database.
When using the
.B start
command,
.IR monetdb (1)
will output diagnostic messages if the requested action failed.  When
encountering an error, one should always consult the logfile of
.IR monetdbd (1)
for more details.  For the
.B kill
command a diagnostic message indicating the database has crashed is
always emitted, due to the nature of that command.
Note that in combination with
.B \-a
the return code of
.IR monetdb (1)
indicates failure if one of the databases had a failure, even though
the operation on other databases was successful.
.TP
\fBget\fP <\fBall\fP | \fIproperty\fP[,\fIproperty\fP[,..]]> [\fIdatabase\fP ...]
Prints the requested properties, or all known properties, for the given
database.  For each property its source and value are printed.  Source
indicates where the current value comes from, e.g. the configuration
file, or a local override.
.TP
\fBset\fP \fIproperty\fP\fB=\fP\fIvalue\fP \fIdatabase\fP [\fIdatabase\fP ...]
Sets property to value for the given database.  For a list of
properties, run
.BR "monetdb get all" .
Most properties require the database to be stopped when set.
.TP
\fBshared=\fP<\fByes\fP|\fBno\fP|\fItag\fP>
Defines if and how the database is being announced to other monetdbds
or not.  If not set to
.B yes
or
.B no
the database is simply announced or not.  Using a string, called
.I tag
the database is shared using that tag, allowing for more sophisticated
usage.  For information about the tag format and use, see section
.I REMOTE DATABASES
in the
.IR monetdbd (1)
manpage.  Note that this property can be set for a running database, and
that a change takes immediate effect in the network.
.TP
\fBnthreads=\fP\fInumber\fP
Defines how many worker threads the server should use to perform main
processing.  Normally, this number equals the number of available CPU
cores in the system.  Reducing this number forces the server to use less
parallelism when executing queries, or none at all if set to
.BR 1 .
.TP
\fBoptpipe=\fP\fIstring\fP
Each server operates with a given optimizer pipeline.  While the default
usually is the best setting, for some experimental uses the pipeline can
be changed.  See the
.IR mserver5 (1)
manpage for available pipelines.  Changing this setting is discouraged
at all times.
.TP
.BR readonly= < yes | no >
Defines if the database has to be started in readonly mode.  Updates are
rejected in this mode, and the server employs some read-only
optimizations that can lead to improved performance.
.TP
\fBnclients=\fP\fInumber\fP
Sets the maximum amount of clients that can connect to this database at
the same time.  Setting this to a high value is discouraged.  A
multiplex-funnel may be more performant, see
.I MULTIPLEX-FUNNEL
below.
.TP
\fBinherit\fP \fIproperty\fP \fIdatabase\fP [\fIdatabase\fP ...]
Like set, but unsets the database-local value, and reverts to inherit
from the default again.
.TP
\fBdiscover\fP [\fIexpression\fP]
Returns a list of remote monetdbds and database URIs
that were discovered by
.IR monetdbd (1).
All databases listed can be connected to via the local MonetDB Database
Server as if it were local databases using their database name.  The
connection is redirected or proxied based on configuration settings.  If
.I expression
is given, only those discovered databases are returned for which their
URI matches the expression.  The expression syntax is described in the
section
.IR EXPRESSIONS .
Next to database URIs the hostnames and ports for monetdbds that
allow to be controlled remotely can be found in the discover list masked
with an asterisk.  These entries can easily be filtered out using an
expression (e.g. "mapi:monetdb:*") if desired.  The control entries come
in handy when one wants to get an overview of available monetdbds in
e.g. a local cluster.  Note that for monetdbd to announce its control
port, the
.I mero_controlport
setting for that monetdbd must be enabled in the configuration file.
.TP
.B \-h
.PD 0
.TP
\fBhelp\fP [\fIcommand\fP]
Shows general help, or short help for a given command.
.TP
.B \-v
.PD 0
.TP
.B version
Shows the version of the
.I monetdb
utility.
.SH EXPRESSIONS
For various options, typically database names, expressions can be used.
These expressions are
limited shell-globbing like, where the * in any position is expanded to
an arbitrary string.  The * can occur multiple times in the expression,
allowing for more advanced matches.  Note that the empty string also
matches the *, hence "de*mo" can return "demo" as match.  To match the
literal '*' character, one has to escape it using a backslash, e.g.
"\e*".
.SH RETURN VALUE
The
.I monetdb
utility returns exit code
.B 0
if it successfully performed the requested command.  An error caused by
user input or database state is indicated by exit code
.BR 1 .
If an internal error in the utility occurs, exit code
.B 2
is returned.
.SH "SEE ALSO"
.IR monetdbd (1),
.IR mserver5 (1)
